JMU JMU - Department of Computer Science
Help Tools
The CS149 Style Guide for Java


Your Java code must comply with the CS149 Style Guide for Java. Note that the examples discussed in the lectures, labs, and readings may not comply with these guidelines as they were prepared by different people and at different times.

1 Terminology

The word "must" indicates that the guideline is mandatory. The word "should" indicates that the guideline is not mandatory but is strongly recommended. The word "may" indicates that the guideline is an exception to another guideline and should be applied rarely.

Mandatory guidelines are of the kind that are used by programming professionals. Recommended guidelines are of the kind that are appropriate for beginning programmers (because they improve understanding) but that are less important for professionals.

2 The Guide

2.1 Organization/Structure

  1. Each class must be in its own file.

    The name of the file and the name of the class must coincide exactly. For example the Queue class should be in a file named Queue.java. Note that Java is case-sensitive (even though some versions of MS-Windows are not).

  2. Each file must end with a blank line (so automated testing tools have a place to insert comments/remarks if necessary).
  3. Methods within a class should be listed in alphabetical order (so they are easier to find with the tools typically used by beginning programmers).

    The only exception to this rule is that all constructors must be listed first. For example, in a Queue class, the constructor(s) should be first, the pop method should be second, and the push method should be third.

  4. All variables should be declared at the top of the relevant class or method (with one exception, because it makes them easier to find).

    In other words, class/instance variables should be declared at the top of the class (before any methods are declared) and variables that are local to a method should be declared at the top of that method (before any other lines of code). The only exception to this rule is that index variables in loops may be declared locally.

  5. All variables should be explicitly initialized.
  6. All variables should be declared and initialized in separate statements (to help you understand the difference).

    So, the following is discouraged: 

                 int age = 35;

    and you should, instead, do the following: 

                 int age;

             age = 35;
  7. Class variables (i.e., static attributes) must be declared before instance variables (i.e., non-static attributes).

    Within each category, public variables must be declared first, followed by protected variables, followed by package variables, followed by private variables.

  8. All variables should be declared alphabetically by their class/type (because it makes them easier to find).

    For example, variables of type double should be declared before variables of type int which should, in turn, be declared before variables of type Node.

2.2 Names

  1. Class names must start with an uppercase letter.

    In addition, each "word" within a class name should start with an uppercase letter. For example, TextMessage and SimpleTrafficMonitor are both appropriate class names.

  2. The names of "constants" (i.e., static final attributes) and local final variables must be in all uppercase.

    Further, "words" within a "constant" name must be delimited by an underscore character. For example, EXTREMELY_UNHEALTHY is an appropriate name for a "constant".

  3. Other variable and method names that contain multiple characters must not start with an uppercase letter.

    Further, each "word" within a variable name should start with an uppercase letter. For example, importantMessage and campusMonitor are both appropriate variable names.

  4. Variable names that consist of a single character may be uppercase.

    In general, even single-character variable names should be lowercase. However, in some situations, mathematical notation uses uppercase letters. In such situations, uppercase variable names may be used. For example, matrices are often written using uppercase letters. So, an expression like (b = A*x) would be appropriate.

  5. Variable and method/function names must be descriptive.

    Variable names like aaa are not appropriate. Index variables and counters can, however, have names like i and j.

2.3 Declarations

  1. Each variable must be declared in its own statements and on its own line (because it encourages commenting).
  2. Visibility modifiers (other than package) must be explicit.

    Do not rely on default visibilities.

  3. Modifiers must appear in the following order: public/private, static, final .
  4. All (non-final) attributes should have private visibility.

    Indeed, they must have private visibility unless there is a very good reason for them not to.

2.4 Comments

  1. Each class must have a descriptive block comment.

    This comment should describe the complete class (rather than the methods in the class) and must include: an @author (containing your name), a @version element (containing the due date), and the line This work complies with the MU Honor Code..

  2. Each method/function must have a descriptive block comment.

    This comment should describe the methods, its parameters, and its return value.

  3. Block comments must use the javadoc format. The comment describing a class must contain @author and @version elements. The comment describing a method must have an @param element for each formal parameter and must have a @return element if the method is not void. These comments must be in the order they are listed and must not be empty.

    javadoc is a program (written in Java) that creates external documentation (in HTML) from block comments. All of the Java documentation was, in fact, created this way. javadoc block comments start with /** and end with */.

  4. Comments in the body of a class should use // rather than /* ... */ (because it makes it easier to "comment out" a section of code while you are debugging).

2.5 White Space

  1. Unary operators must not be separated from their operands by any white space.
  2. There must be an empty line after headers, imports, fields/attributes, constructors, and methods.
  3. There must be a space after cast operators, commas and //.

2.6 Indentation and Blocks

  1. Three spaces must be used for each indentation level.

    Except for array initializations, which must be indented 8 spaces. Also, tabs characters must not be used.

  2. The { must appear at the end of the line containing conditional and loop structures.
  3. The { must appear at the end of the line containing conditional and loop structures.
  4. The } must appear at the start of a new line (because it makes it easy to identify the end of a block). The else {, if there is one, must appear on the same line (after a space).
  5. Code must not contain empty blocks or empty statements.
  6. All blocks (even if one line) must be surrounded by a { and }.

2.7 Intelligibility

  1. Attributes (i.e., instance variables) and non-static methods must be preceded by this. (so that you can easily distinguish t hem from local variables).
  2. Lines must be short (i.e., less than 80 characters) (so that you can see a complete line even on a low-resolution display).
  3. Files must be short (i.e., less than 2000 lines) (to ensure that they are cohesive).
  4. There must be no more than one statement per line.
  5. switch statements should have a default clause.
  6. The default clause should be after all case clauses in a switch statement.
  7. case clauses in switch statements should not fall-through
  8. Actual parameters must not be assigned values.
  9. A single method must have no more than two return statements.
  10. Complicated Boolean return statements must be avoided.
  11. Boolean expressions must be simplified.
  12. Block statements (i.e., statements within a {}) must only be used with if statements and loops.
  13. Subexpressions must not contain assignments.
  14. Static imports must not be used (because it makes it difficult to see which class a method belongs to).
  15. Methods must not be longer than 150 lines (long methods should almost always be broken up into multiple smaller methods, each with a well-defined purpose).
  16. Unnecessary parentheses must be omitted (because they tend to demonstrate a lack of understanding and/or confusion).
  17. Method must not be more than 150 lines long (because long methods are difficult to understand).

2.8 Reliability and Robustness

  1. Local variables and (most) parameters should not shadow class attributes.

    Parameters in constructors and setters may.

  2. String literals must not be used with the == or != operators.
  3. The * wildcard must not be used in import statements (because it makes it difficult to see dependencies).

    They may be used with JUnit packages.

  4. for loop control variables must not be changed within the body of the loop.
  5. A class must not contain redundant imports.
  6. A class must not contain unused imports.
  7. long literals must use an uppercase L (because the lowercase l is difficult to distinguish from a 1).
  8. static imports statements must not be used. (because many tools require it).

    They may be used with JUnit packages.

  9. All classes must end with a newline character (because many tools require it).
  10. Files must not contain tab characters (because they are interpreted differently on different platforms). Note that must editors can be configured to replace tabs with spaces.

3 Style Humor

Different people have different opinions about what is "stylish". This leads to many fights (and some jokes).

../lectures/comics/Hackles-Style.png
(Courtesy of Hackles)

http://imgs.xkcd.com/comics/code_quality.png
(Courtesy of xkcd)

http://imgs.xkcd.com/comics/code_quality_2.png
(Courtesy of xkcd)

Department of Computer Science

Copyright 2020